PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / datecls.exe / DATECLS4.DOC < prev next >

Wrap

Text File | 1993-03-07 | 14.8 KB | 349 lines

======================================================= Documentation for "The Killer Date Class!" Version 4.00 ======================================================= History ======= In the beginning Steve Marcus (CIS 72007,1233) posted a basic date manipulation/arithmetic class produced with Borland C++ 2.0 in the BPROGB forum, with a request for suggestions and enhancements. This was on 6/19/91. A rather enterprising gentleman by the name of Eric Simon (CIS 70540,1522) accepted the challenge, and produced a new and improved version in the course of a project he was developing at work. He contributed the results to the forum on 6/29/91, also inviting enhancements and comments. About that time yet another enterprising gentleman named Christopher Hill developed a need for a universal date conversion routine for use in a business project he was developing as well. Browsing the same forum, he encountered Eric's class, which provided much of the functionality he needed - the basic julian-gregorian and day of week conversion algorithms - relieving him of the task of researching or re-inventing them. Eric had also added overloaded + and - operators for incrementing date objects by integer days, as well as several print functions. Chris needed additional features for his implementations, thus was born versions 3.0 and 3.1(Hill & Simon). Well, almost a year later I sent out an SOS for a date class so _I_ didn't have to re-invent the wheel and lo-and-behold Chris responded. Thus begins the saga of version 4.0! I would like to take this opportunity to do a little witnessing: I looked all over for a date class that would suit my needs! I reviewed many implementations from strangers and friends alike and I am here to tell ya' folks, "It don't 'git no bedder 'n dis!" This class is _VERY_ cool! Now I'm not trying to say that there's no more room for enhancements (I'd really be crazy then!), but I am saying that if your looking for a _GOOD_ date class (I'd say commercial quality because I have yet to see a commercial product that implemented a date class to my satisfaction!) then this is it! So jump in and add to it, make it better and we'll SAVE THE WORLD! (Ok, so I got a little carried away at the end. Just a little...) No, but really... This is a truly pleasing example of co-operation among professionals, and an "object" study in the code reusability of OOP, resulting in three releases of one class within a single month by three different analysts who have never met, and yet another upgrade almost a year later by a fourth analyst (myself) and none of us have yet to meet! Chris thanks Steve and Eric for their inspiration and generousity, and I thank all three as well and hereby contribute my additions to the public domain. I believe any of us would welcome further comments, suggestions and enhancements as well. Good luck! May the quest for the perfect date class continue! v4.1 Kenneth A. Argo - 71241,3635 3/7/93 v4.0 Charles Price - 70541,3651 6/27/92 v3.1 Hill & Simon - 8/05/91 v3.0 Christopher Hill - 72030,2606 7/11/91 v2.0 Eric Simon - 70540,1522 6/29/91 v1.0 Steve Marcus - 72007,1233 6/16/91 Implementation Notes ==================== All versions prior to 4.0 were written specifically for a Borland C++ compiler. However, version 4.0 was written specifically for Microsoft C++ 7.0. I too have attempted to optimize the code including the specification of const where applicable, the passing of references where advisable, and the use of constructor initializers where needed. However, I have not made an exhaustive analysis of this subject either. To get the best overview of the class capabilities run the demo program. It may not look pretty, but with a printout of a sample run and the code you should be able to get a really good feel for it. I have included a samples run at the end of this file in case someone doesn't want to take the time to compile the demo program. This ZIP file contains: DATECLS4.DOC - this file DATECLS4.H - the header file DATECLS4.CPP - the member functions DATEDEMO.CPP - a test program (and a messy one at that!) DATECLS4.LIB - a lib file so you can use it even if you don't have MSC7.0, or you just don't feel like fussin' with it! (Added in v4.0) Future possibilities for enhancement include ============================================ 1. Adding a derived Time class, for those applications which require the ability to track more than just dates. This would allow the manipulation of times for all dates (not just since 1980), and arithmetic calculations as well. Additions/Changes to Version 4.1 ================================ Fixed date display when using the * operator to get a string pointer. The code would return xx/xx/ xx if you only supplied a 2 digit year. Optimized the * operator so Invalid Dates would use a common "invalid date" text pointer. Fixed the +, - and * operators to get rid cases where memory leaks would occur. Fixed some variable casts so the code can be compiled with /W4 Added a destructor tp delete items created dynamically on behalf of the object (ie. char *). Release Documentation for Version 4.0 ===================================== Most of the modifications made to version 3.1 were to expand the public interface. Below is a list of new features in v4.0: 1. Date &Set() - Sets self to current system date; this may also be accomplished by passing initializing a date object like so: Date oDate1("Today"); // See demo for examples 2. Date &Set(long lJulian) - Sets self to the specified julian date 3. Date &Set(int nMonth, int nDay, int nYear) - Sets self to specified month, day, and year. The year must be 4 numbers long, not 2. 4. Date &AddWeeks(int nCount = 1) - Add or subtract(use a negative int) a specified number of weeks to/from self 5. Date &AddMonths(int nCount = 1) - Add or subtract(use a negative int) a specified number of months to/from self 6. Date &AddYears(int nCount = 1); - Add or subtract(use a negative int) a specified number of years to/from self 7. int Day() const - Returns numeric day of the month for self 8. int DaysInMonth() - Returns number of days in month (1..31) 9. int FirstDOM() const - Returns the First Day Of Month for self as a numeric (1..7) 10. char *CDOW() - Returns character Day Of Week ('Sunday'..'Saturday') 11. int NDOW() const - Returns the numeric day of the week for self(1..7) 12. int WOM() - Returns numeric Week Of Month (1..6) 13. int WOY() - Returns numeric Week Of Year (1..52) 14. char *CMonth() - Character Month name ("January") 15. int NMonth() const - Month Number (1..12) 16. Date BOM() - Returns a new date object that is the First Date Of the Month in self. For example: Date oDate1; Date oDate2("Today"); oDate1 = oDate2.BOM(); 17. Date EOM() - Returns a new date object that is the Last Date Of the Month in self. (See example in 16 above) 18. int NYear4() const - Returns the numeric value of the year for self in the form 1992. 19. Date BOY() - Returns a new date object that is the First Date Of the Year in self. (See example 16 above) 20. Date EOY() - Returns a new date object that is the Last Date Of the Year in self. (See example 16 above) 21. Added overloaded operators for + and - to accept int's. 22. Added overloaded operators for ++ and -- for Postfix notation 23. Switched from the Borland style DOS date structure(date) to the Microsoft version(_dosdate_t). Suggestions and general comments are always welcome! Enjoy! Chuck :-} Release Documentation for Version 3.1 ===================================== Subsequent to release 3.00, we (Hill & Simon) decided to collaborate on several further releases of this date class. This, the first, contains two new features, as well as a few minor bug fixes. 1. There was a minor bug in the original Computer Language julian/gregorian date conversion routines having to do with negative years. 2. The isLeapYear function did not take into account that, prior to 1582, years ending in 00 were also leap years. 3. The two-dimensional array of the number of days in each month has been eliminated in favor of a computational approach. 4. The function Date::setFormat(XXXX) maintains a static variable (one occurance for all Date objects, which controls the format which the << operator uses to print objects. "XXXX" can be MONTH, MDY, DAY, FULL, or EUROPEAN. The setting defaults to MDY, but once altered, remains altered until reset by another call to setFormat. The function Date::setOption(Option, Action) maintains a similar static variable which enables certain print formatting options. Available options at this point are: NO_CENTURY -- Suppress the printing of the century when in the MDY format (ex: 01/01/91 instead of 01/01/1991). DATE_ABBR -- Abbreviate month and day names when printing in the MONTH, DAY, FULL or EUROPEAN formats. (ex. MON, TUE, JAN, FEB, etc.) The length or the abbreviation is controlled by a DEFINED constant in DATECL31.HPP named ABBR_LENGTH, preset to 3. "Action" is either ON or OFF, and defaults to ON. (Example, the call Date::setOption(NO_CENTURY) turns on the century suppression option, and it remains set until the call Date::setOption(NO_CENTURY, OFF) is made. More features, including further expanded print formatting features, the derived Time class mentioned above, conversion into various calendar formats (Jewish, Chinese, Arabic, etc.), ability to increment Date objects by years and months instead of merely days, holiday computations, and more are planned. Sample run of DATEDEMO.EXE v4.0 =============================== Date Class v4.0 Demo Saturday, October 20, 1962 Monday Tuesday, October 10, 1995 Tuesday, October 30, 1962 5 October 1962 -14 8/6/1991 Tommorrow= Sunday, July 14, 1991 a1 (7-14-91) < 8-01-91 ? ==> TRUE a1 (7-14-91) > 8-01-91 ? ==> FALSE a1 (7-14-91)== 7-14-91 ? ==> TRUE a1 (7-14-91)== a3 (7-14-91) ? ==> TRUE a1 (7-14-91)== a4 (7-15-91) ? ==> FALSE Today is: 6/28/1992 Today (a4) is: 6/28/1992 Today + 4 is: 7/2/1992 Today - 4 is: 6/24/1992 =========== Leap Year Test =========== Wednesday, January 15, 1992 Leap day of year: 15 Tuesday, February 16, 1993 non-Leap day of year: 47 =========== eom test ============== b1.eom() (s/b 2/28/91) ==> 2/28/1991 ================== getDate test ===================== a1.getDate() (s/b 2/16/1993) ==> 2/16/1993 ================== string assignment test ==================== a1 as a string (s/b 2/16/1993) ==> 2/16/1993 ================== setFormat test ============================ a1 (s/b FULL format) ==> Tuesday, February 16, 1993 a1 (s/b EUROPEAN format) ==> 16 February 1993 ================== setOption test ============================ Date abbreviation ON a1 (s/b MONTH format) ==> Feb a1 (s/b DAY format) ==> Tue a1 (s/b FULL format) ==> Tue, Feb 16, 1993 a1 (s/b EUROPEAN format) ==> 16 Feb 1993 Century suppression ON a1 (s/b MDY format) ==> 2/16/93 Century suppression OFF a1 (s/b MDY format) ==> 2/16/1993 Century suppression ON a1 (s/b MDY format) ==> 2/16/93 a1 (s/b FULL format) ==> Tue, Feb 16, 1993 =============== Version 4.0 Enhancement Test ================= ---------- Set Stuff ----------- First, 'Set' to today... Before 'Set' => Saturday, November 26, 1966 After 'Set' => Sunday, June 28, 1992 Set to 11/26/66 => Saturday, November 26, 1966 Current Julian => 2439455 Set to Julian 2450000L => Tuesday, October 10, 1995 See! => 2450000 ---------- Add Stuff ----------- Start => Tuesday, October 10, 1995 Add 4 Weeks => Tuesday, November 7, 1995 Sub 1 Month => Saturday, October 7, 1995 Add 2 Years => Tuesday, October 7, 1997 ---------- Misc Stuff ----------- The date aboves' day of the month is => 7 There are 31 days in this month. The first day of this month lands on 4 This day happens to be Tuesday the 3 day of the week, on the 41 week of the year, on the 2 week of the month, (which is October) the 10nth month in the year. The year alone is 1997 ---------- First and Last Stuff ----------- The first date of this month is Monday, June 1, 1992 The last date of this month is Tuesday, June 30, 1992 The first date of this year is Wednesday, January 1, 1992 The last date of this year is Thursday, December 31, 1992 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 4,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394